Move GtkMenuShell docs inline

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index ebc9d6b070f2cd84b066dedc6b11ad373c4060d9..1cea81d52d79088c80a4b9bcb47255d5038e1b12 100644 (file)
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -35,6 +35,7 @@ gtklayout.sgml
 gtklinkbutton.sgml
 gtkmain.sgml
 gtkmenubar.sgml
+gtkmenushell.sgml
 gtkmessagedialog.sgml
 gtknotebook.sgml
 gtkobject.sgml

diff --git a/docs/reference/gtk/tmpl/gtkmenushell.sgml b/docs/reference/gtk/tmpl/gtkmenushell.sgml
deleted file mode 100644 (file)
index 2153098..0000000
--- a/docs/reference/gtk/tmpl/gtkmenushell.sgml
+++ /dev/null
@@ -1,224 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkMenuShell
-
-<!-- ##### SECTION Short_Description ##### -->
-A base class for menu objects
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-A #GtkMenuShell is the abstract base class used to derive the 
-#GtkMenu and #GtkMenuBar subclasses.  
-</para>
-
-<para>
-A #GtkMenuShell is a container of #GtkMenuItem objects arranged in a 
-list which can be navigated, selected, and activated by the user to perform
-application functions.  A #GtkMenuItem can have a submenu associated with it,
-allowing for nested hierarchical menus.
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkMenuShell ##### -->
-<para>
-The #GtkMenuShell-struct struct contains the following fields.
-(These fields should be considered read-only. They should never be set by
-an application.)
-
-<informaltable pgwide="1" frame="none" role="struct">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>#GList *children;</entry>
-<entry>The list of #GtkMenuItem objects contained by this #GtkMenuShell.
-</entry>
-</row>
-</tbody></tgroup></informaltable>
-</para>
-
-
-<!-- ##### SIGNAL GtkMenuShell::activate-current ##### -->
-<para>
-An action signal that activates the current menu item within the menu
-shell.
-</para>
-
-@menushell: the object which received the signal.
-@force_hide: if TRUE, hide the menu after activating the menu item.
-
-<!-- ##### SIGNAL GtkMenuShell::cancel ##### -->
-<para>
-An action signal which cancels the selection within the menu shell.
-Causes the GtkMenuShell::selection-done signal to be emitted.
-</para>
-
-@menushell: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuShell::cycle-focus ##### -->
-<para>
-
-</para>
-
-@menushell: the object which received the signal.
-@arg1: 
-
-<!-- ##### SIGNAL GtkMenuShell::deactivate ##### -->
-<para>
-This signal is emitted when a menu shell is deactivated.
-</para>
-
-@menushell: the object which received the signal.
-
-<!-- ##### SIGNAL GtkMenuShell::move-current ##### -->
-<para>
-An action signal which moves the current menu item in the direction 
-specified by @direction.
-</para>
-
-@menushell: the object which received the signal.
-@direction: the direction to move.
-
-<!-- ##### SIGNAL GtkMenuShell::move-selected ##### -->
-<para>
-
-</para>
-
-@menushell: the object which received the signal.
-@arg1: 
-@Returns: 
-
-<!-- ##### SIGNAL GtkMenuShell::selection-done ##### -->
-<para>
-This signal is emitted when a selection has been completed within a menu
-shell.
-</para>
-
-@menushell: the object which received the signal.
-
-<!-- ##### ARG GtkMenuShell:take-focus ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_menu_shell_append ##### -->
-<para>
-Adds a new #GtkMenuItem to the end of the menu shell's item list.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-@child: The #GtkMenuItem to add.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_prepend ##### -->
-<para>
-Adds a new #GtkMenuItem to the beginning of the menu shell's item list.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-@child: The #GtkMenuItem to add.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_insert ##### -->
-<para>
-Adds a new #GtkMenuItem to the menu shell's item list at the position
-indicated by @position. 
-</para>
-
-@menu_shell: a #GtkMenuShell.
-@child: The #GtkMenuItem to add.
-@position: The position in the item list where @child is added.
-Positions are numbered from 0 to n-1.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_deactivate ##### -->
-<para>
-Deactivates the menu shell.  Typically this results in the menu shell
-being erased from the screen.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_select_item ##### -->
-<para>
-Selects the menu item from the menu shell.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-@menu_item: The #GtkMenuItem to select.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_select_first ##### -->
-<para>
-
-</para>
-
-@menu_shell: 
-@search_sensitive: 
-
-
-<!-- ##### FUNCTION gtk_menu_shell_deselect ##### -->
-<para>
-Deselects the currently selected item from the menu shell, if any.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_activate_item ##### -->
-<para>
-Activates the menu item within the menu shell.
-</para>
-
-@menu_shell: a #GtkMenuShell.
-@menu_item: The #GtkMenuItem to activate.
-@force_deactivate: If TRUE, force the deactivation of the menu shell
-after the menu item is activated.
-
-
-<!-- ##### FUNCTION gtk_menu_shell_cancel ##### -->
-<para>
-
-</para>
-
-@menu_shell: 
-
-
-<!-- ##### FUNCTION gtk_menu_shell_set_take_focus ##### -->
-<para>
-
-</para>
-
-@menu_shell: 
-@take_focus: 
-
-
-<!-- ##### FUNCTION gtk_menu_shell_get_take_focus ##### -->
-<para>
-
-</para>
-
-@menu_shell: 
-@Returns: 
-
-
-<!-- ##### ENUM GtkMenuDirectionType ##### -->
-<para>
-An enumeration representing directional movements within a menu.
-</para>
-
-@GTK_MENU_DIR_PARENT: To the parent menu shell.
-@GTK_MENU_DIR_CHILD: To the submenu, if any, associated with the item.
-@GTK_MENU_DIR_NEXT: To the next menu item.
-@GTK_MENU_DIR_PREV: To the previous menu item.
-

diff --git a/gtk/gtkenums.h b/gtk/gtkenums.h
index 76ea88578f08f0e2cbae6d444cb1f5ccceaffee6..e62e43e107d919d74293fe84dcb9d3695895af30 100644 (file)
--- a/gtk/gtkenums.h
+++ b/gtk/gtkenums.h
@@ -245,7 +245,15 @@ typedef enum
   GTK_JUSTIFY_FILL
 } GtkJustification;
 
-/* Menu keyboard movement types */
+/**
+ * GtkMenuDirectionType:
+ * @GTK_MENU_DIR_PARENT: To the parent menu shell
+ * @GTK_MENU_DIR_CHILD: To the submenu, if any, associated with the item
+ * @GTK_MENU_DIR_NEXT: To the next menu item
+ * @GTK_MENU_DIR_PREV: To the previous menu item
+ *
+ * An enumeration representing directional movements within a menu.
+ */
 typedef enum
 {
   GTK_MENU_DIR_PARENT,

diff --git a/gtk/gtkmenushell.c b/gtk/gtkmenushell.c
index 1bbbc177be601207f905e583016a075e1712161f..172b5766c01d5500f5401153040f8e47cb557fdc 100644 (file)
--- a/gtk/gtkmenushell.c
+++ b/gtk/gtkmenushell.c
@@ -24,6 +24,19 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/**
+ * SECTION:gtkmenushell
+ * @Title: GtkMenuShell
+ * @Short_description: A base class for menu objects
+ *
+ * A #GtkMenuShell is the abstract base class used to derive the
+ * #GtkMenu and #GtkMenuBar subclasses.
+ *
+ * A #GtkMenuShell is a container of #GtkMenuItem objects arranged
+ * in a list which can be navigated, selected, and activated by the
+ * user to perform application functions. A #GtkMenuItem can have a
+ * submenu associated with it, allowing for nested hierarchical menus.
+ */
 #include "config.h"
 
 #include "gtkbindings.h"
@@ -231,6 +244,12 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
   klass->insert = gtk_menu_shell_real_insert;
   klass->move_selected = gtk_menu_shell_real_move_selected;
 
+  /**
+   * GtkMenuShell::deactivate:
+   * @menushell: the object which received the signal
+   *
+   * This signal is emitted when a menu shell is deactivated.
+   */
   menu_shell_signals[DEACTIVATE] =
     g_signal_new (I_("deactivate"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -240,6 +259,13 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
                   _gtk_marshal_VOID__VOID,
                   G_TYPE_NONE, 0);
 
+  /**
+   * GtkMenuShell::selection-done:
+   * @menushell: the object which received the signal
+   *
+   * This signal is emitted when a selection has been
+   * completed within a menu shell.
+   */
   menu_shell_signals[SELECTION_DONE] =
     g_signal_new (I_("selection-done"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -249,6 +275,14 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
                   _gtk_marshal_VOID__VOID,
                   G_TYPE_NONE, 0);
 
+  /**
+   * GtkMenuShell::move-current:
+   * @menushell: the object which received the signal
+   * @direction: the direction to move
+   *
+   * An keybinding signal which moves the current menu item
+   * in the direction specified by @direction.
+   */
   menu_shell_signals[MOVE_CURRENT] =
     g_signal_new (I_("move-current"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -259,6 +293,14 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
                   G_TYPE_NONE, 1,
                   GTK_TYPE_MENU_DIRECTION_TYPE);
 
+  /**
+   * GtkMenuShell::activate-current:
+   * @menushell: the object which received the signal
+   * @force_hide: if %TRUE, hide the menu after activating the menu item
+   *
+   * An action signal that activates the current menu item within
+   * the menu shell.
+   */
   menu_shell_signals[ACTIVATE_CURRENT] =
     g_signal_new (I_("activate-current"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -269,6 +311,13 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
                   G_TYPE_NONE, 1,
                   G_TYPE_BOOLEAN);
 
+  /**
+   * GtkMenuShell::cancel:
+   * @menushell: the object which received the signal
+   *
+   * An action signal which cancels the selection within the menu shell.
+   * Causes the #GtkMenuShell::selection-done signal to be emitted.
+   */
   menu_shell_signals[CANCEL] =
     g_signal_new (I_("cancel"),
                   G_OBJECT_CLASS_TYPE (object_class),
@@ -278,6 +327,14 @@ gtk_menu_shell_class_init (GtkMenuShellClass *klass)
                   _gtk_marshal_VOID__VOID,
                   G_TYPE_NONE, 0);
 
+  /**
+   * GtkMenuShell::cycle-focus:
+   * @menushell: the object which received the signal
+   * @direction: the direction to cycle in
+   *
+   * A keybinding signal which moves the focus in the
+   * given @direction.
+   */
   menu_shell_signals[CYCLE_FOCUS] =
     g_signal_new_class_handler (I_("cycle-focus"),
                                 G_OBJECT_CLASS_TYPE (object_class),
@@ -447,6 +504,14 @@ gtk_menu_shell_dispose (GObject *object)
   G_OBJECT_CLASS (gtk_menu_shell_parent_class)->dispose (object);
 }
 
+/**
+ * gtk_menu_shell_append:
+ * @menu_shell: a #GtkMenuShell
+ * @child: The #GtkMenuItem to add
+ *
+ * Adds a new #GtkMenuItem to the end of the menu shell's
+ * item list.
+ */
 void
 gtk_menu_shell_append (GtkMenuShell *menu_shell,
                        GtkWidget    *child)
@@ -454,6 +519,14 @@ gtk_menu_shell_append (GtkMenuShell *menu_shell,
   gtk_menu_shell_insert (menu_shell, child, -1);
 }
 
+/**
+ * gtk_menu_shell_prepend:
+ * @menu_shell: a #GtkMenuShell
+ * @child: The #GtkMenuItem to add
+ *
+ * Adds a new #GtkMenuItem to the beginning of the menu shell's
+ * item list.
+ */
 void
 gtk_menu_shell_prepend (GtkMenuShell *menu_shell,
                         GtkWidget    *child)
@@ -461,6 +534,16 @@ gtk_menu_shell_prepend (GtkMenuShell *menu_shell,
   gtk_menu_shell_insert (menu_shell, child, 0);
 }
 
+/**
+ * gtk_menu_shell_insert:
+ * @menu_shell: a #GtkMenuShell
+ * @child: The #GtkMenuItem to add
+ * @position: The position in the item list where @child
+ *     is added. Positions are numbered from 0 to n-1
+ *
+ * Adds a new #GtkMenuItem to the menu shell's item list
+ * at the position indicated by @position.
+ */
 void
 gtk_menu_shell_insert (GtkMenuShell *menu_shell,
                        GtkWidget    *child,
@@ -489,6 +572,15 @@ gtk_menu_shell_real_insert (GtkMenuShell *menu_shell,
   gtk_widget_set_parent (child, GTK_WIDGET (menu_shell));
 }
 
+/**
+ * gtk_menu_shell_deactivate:
+ * @menu_shell: a #GtkMenuShell
+ *
+ * Deactivates the menu shell.
+ *
+ * Typically this results in the menu shell being erased
+ * from the screen.
+ */
 void
 gtk_menu_shell_deactivate (GtkMenuShell *menu_shell)
 {
@@ -1173,6 +1265,13 @@ gtk_menu_shell_get_item (GtkMenuShell *menu_shell,
 
 /* Handlers for action signals */
 
+/**
+ * gtk_menu_shell_select_item:
+ * @menu_shell: a #GtkMenuShell
+ * @menu_item: The #GtkMenuItem to select
+ *
+ * Selects the menu item from the menu shell.
+ */
 void
 gtk_menu_shell_select_item (GtkMenuShell *menu_shell,
                             GtkWidget    *menu_item)
@@ -1232,6 +1331,13 @@ gtk_menu_shell_real_select_item (GtkMenuShell *menu_shell,
     gtk_widget_activate (priv->active_menu_item);
 }
 
+/**
+ * gtk_menu_shell_deselect:
+ * @menu_shell: a #GtkMenuShell
+ *
+ * Deselects the currently selected item from the menu shell,
+ * if any.
+ */
 void
 gtk_menu_shell_deselect (GtkMenuShell *menu_shell)
 {
@@ -1247,6 +1353,15 @@ gtk_menu_shell_deselect (GtkMenuShell *menu_shell)
     }
 }
 
+/**
+ * gtk_menu_shell_activate_item:
+ * @menu_shell: a #GtkMenuShell
+ * @menu_item: the #GtkMenuItem to activate
+ * @force_deactivate: if %TRUE, force the deactivation of the
+ *     menu shell after the menu item is activated
+ *
+ * Activates the menu item within the menu shell.
+ */
 void
 gtk_menu_shell_activate_item (GtkMenuShell *menu_shell,
                               GtkWidget    *menu_item,